.\"
.\"
.TH DYNAMO 1 "May 2, 2014" "Ada Web Application"
.SH NAME
dynamo - Ada Application Generator
.SH SYNOPSIS
.B dynamo
[ -v ] [ -o
.I directory
] [ -t
.I templates
] [ -c
.I config-dir
]
.I command
.br
.SH DESCRIPTION
\fIdynamo\fR is a command to help developers write an Ada Application using the
.B ASF
,
.B ADO
,
.B AWA
or
.B Gtk
libraries.  \fIdynamo\fR provides several commands to perform one specific task in
the development process.
.\"
.PP
First the
.B create-project
command will be used to initiate a new project.  The project name is used at this stage
to configure the name of the root Ada package for the application.
.\""
.PP
The
.B add-model
command will be used to create a database table mapping file.  The database mapping file
describes how to map a database table into an Ada record type for the
.B ADO
framework.  The
.B generate
command is then used to build the Ada model files from the database mapping files or from a UML model.
At the same time, it generates the SQL database creation schemas for MySQL and SQLite databases.
.PP
The
.B add-page
command is then used to add web pages for the application.  When a new application
layout is necessary, the
.B add-layout
command can be used.
.\"
.PP
To deploy an application on a production server, the
.B dist
command can be used to prepare the distribution tree, merge various files and directories,
perform CSS and Javascript compression by using the
.B yui-compressor
or other tools.
.\"
.PP
.I dynamo
uses the
.B dynamo.xml
file to get information on the project and customize the generation.  It scans the
GNAT project files to obtain the dependencies between several
.I dynamo
components.
.\"
.SH OPTIONS
The following options are recognized by \fIdynamo\fR:
.TP 5
-v
Prints the
.I dynamo
version as well as various installation and configuration paths.
.TP 5
-o directory
.br
Specifies the directory where result files are created.  The default is the current directory.
.TP 5
-c directory
.br
Specifies the configuration directory which contains \fIdynamo\fR configuration
files as well as template files.
.TP 5
-t directory
.br
Specifies the templates directory.  This option can be used to override the
templates provided by \fIdynamo\fR.
.\"
.SH COMMANDS
.\"
.SS The create-project command
.RS 0
dynamo \fBcreate-project\fR [-l \fI{apache|gpl|bsd3|mit|proprietary}\fR] [--web] [--gtk] [--tool] [--ado] \fIname\fR \fIauthor\fR \fIemail\fR
.RE
.PP
Create a new project in the current working directory or in the
directory specified by the
.I -o
option.  The project name should be a valid Ada identifier.  It represents the Ada root
package name for the project.  The command creates a set of Ada files, a configure script,
a Makefile as well as a
.I gnatmake
build file.  The application can be immediately compiled to obtain a web server that is ready
to run.  The
.B -l
option allows to choose the license headers.  The tool supports the generation
of Apache, the GNU license or a proprietary license.  The author's name and email address
can be specified in the command line so that the license headers integrates them correctly.
.\"
.PP
The project type is controlled by one of the
.B --web
,
.B --tool
,
.B --gtk
or
.B --ado
option.  When
.B --ado
is specified, a command line project using Ada Database Objects is generated.  This type of
project does not use Ada Server Faces nor Ada Web Application.  When
.B --web
option is specified, a full web application based on ASF and AWA is created.  The
.B --web
is the default if no other option is specified.
.\"
The
.B --gtk
option generates a Gtk Ada application.
.\"
.SS The dist command
.RS 0
dynamo \fBdist \fItarget-dir\fR [\fIpackage.xml\fR]\fR
.RE
.PP
After a web project is compiled, this command allows to build the distribution files that
must be installed on the server.  The
.I dist
command reads a
.I package.xml
file which describes how to make such distribution by specifying the files that must
be copied.  For some files, it is possible to execute an external application that will
do some transformation on the source file and prepare it for the installation.
For example the
.I package.xml
description can compress the Javascript and CSS files by using the
.B yui-compressor
tool.  Images can be optimized by using
.B pngcrush
or
.B jpegtran.
.\"
.SS The create-database command
.RS 0
dynamo \fBcreate-database \fImodel [connection] admin-user [admin-password]\fR\fR
.RE
.PP
The create-database command creates the database used by the application.
The database schema file is stored in the directory identified by
.I model
and is generated by the
.I generate
command.
The database connection string is optional.  The default database connection string
is read from the
.I database
property in the
.B dynamo.xml
configuration file.  The connection string has the following form: 
.\"
.RS 0
\fIdriver\fR://\fIhost\fR:\fIport\fR/\fIdatabase\fR
.RE
.PP
The command will connect to the database server specified by the connection string.
It will use the admin user for this connection. The database is created if it does
not yet exist. If a user is specified in the connection string, a grant command is
issued to create that user and allow him to access the new database.
.PP
Example of connection string for MySQL database:
.\"
.RS 0
mysql://localhost:3306/my_db?user=joe&password=admin
.RE
.\"
.PP
The MySQL server is running on localhost and TCP/IP port 3306.  The database name is
.I my_db
and the user
.I joe
is created for the application with the password
.I admin.
.PP
The database tables are created by using the
.I create-name-driver.sql
script where
.I name
represents the Dynamo project name.
.\"
.SS The create-plugin command
.RS 0
dynamo \fBcreate-plugin \fIname\fR [ada | web]\fR
.RE
.PP
Create a new plugin for the current project.  The plugin sources are created in the
\fBplugins/\fR\fIname\fR
directory.  The optional last argument controls whether the new plugin contains
Ada sources or is a Web plugin.  The plugin can be seen as a separate small
.I Dynamo
project that is used by a project.  Once create, the other
.I Dynamo
commands can be executed in the new plugin.
.\"
.\"
.SS The add-layout command
.RS 0
dynamo \fBadd-layout \fIname\fR\fR
.RE
.PP
Create a new XHTML layout file.  The layout file is an XHTML facelet template which can
be used by a web page to provide a common presentation layout.  When the project is
created, at least one layout is proposed.  By adding a new layout, the application
can provide different presentation styles.  The layout files are stored in the
.B web/WEB-INF/layouts
directory.
.\"
.\"
.SS The add-page command
.RS 0
dynamo \fBadd-page \fIname\fR\fR
.RE
.PP
Create a new presentation page.  The presentation page is an XHTML facelet file
which contains HTML code as well as ASF facelet components.  The presentation
pages are stored in the
.B web
directory.
.\"
.\"
.SS The add-model command
.RS 0
dynamo \fBadd-model [\fImodule\fR] \fIname\fR\fR
.RE
.PP
Create a new database table model mapping.  The model mapping is an XML file that
describes how to map a database table into an Ada type.
The model mappings are stored in the
.B db
directory.  The database table is mapped to an Ada tagged record in the package
\fB\fIproject-name\fR\fR.\fImodule\fR.Model\fR if a module name is passed otherwise the package
will have the name \fB\fIproject-name\fR.Model\fR.  The Ada record will have the name
\fB\fIname\fR_Ref\fR.
.\"
.SS The add-module command
.RS 0
dynamo \fBadd-module \fIname\fR\fR
.RE
.PP
Add a new module to the project.  The module is composed of a set of Ada files
and a set of XHTML presentation files.  The
.I name
parameter is the name of the Ada child package that represents the module.
This is also the name of the directory that will contain the specific XHTML files
used for the module.
The following Ada packages are generated:
.\"
.RS 0
package \fIproject\fR.\fImodule\fR;
.br
package \fIproject\fR.\fImodule\fR.Beans;
.br
package \fIproject\fR.\fImodule\fR.Modules;
.RE
.PP
where
.I project
is the project name (defined by the
.B create-project
command) and
.I module
is the new module name.
.PP
The
.I Module
package defines the main module data type with the initialization steps.
The
.I Beans
package defines the Ada bean types which are specific to the module.
Each Ada bean type must be registered in the
.I Module
package.  The generated files are intended to be modified to implement the
module functionality.
.\"
.SS The add-module-operation command
.RS 0
dynamo \fBadd-module-operation \fImodule\fR \fIentity\fR \fIoperation\fR\fR
.RE
.PP
Add an operation in a module to perform some action on a database entity.
The
.I module
is the name of the module in the application and
.I entity
is the name of the database table. The
.I operation
is the name of the Ada procedure and must be a valid Ada identifier.
The generated operation has the following signature:
.\"
.RS 0
  procedure <operation>
    (Module : in <module>_Module;
.br
     Entity : in out <project>.<module>.Models.<entity>_Ref'Class);
.RE
.PP
where
.I project
is the project name.  The command modifies the module package specification
to add the necessary Ada
.I with
clauses and declare the new operation.  It modifies the module package body
to add some other necessary Ada
.I with
clauses and implement the new operation.  The default implementation creates
a database transaction, saves the entity and commits the transaction.
.\"
.SS The build-doc command
.RS 0
dynamo \fBbuild-doc \fIdirectory\fR\fR
.RE
.PP
Extract the documentation from the project source files and generate the
project documentation.  The Ada specification files are scanned and the
package specification header comment is used as the main structure for
the project documentation.  The XML files are also scanned and the documentation
is extracted from these files.  It can be merged together with other
documentation to build up the final project user documentation.
.\"
.\"
.SS The info command
.RS 0
dynamo \fBinfo\fR
.RE
.PP
Report information about the current project.  This command scans the GNAT projects to
find the
.I dynamo
components dependencies.  It then lists the GNAT projects and the
.I dynamo
components that are used by the current project.
.\"
.SS The help command
.RS 0
dynamo \fBhelp \fIname\fR\fR
.RE
.PP
Give an help description about a command.
.\"
.SS The generate command
.RS 0
dynamo \fBgenerate [--package \fIname\fR] [\fImodel ... \fR]\fR
.RE
.PP
Generate the Ada model implementation from the XML model mappings or from a UML model.
The Ada model files are generated in the
.B src/model
directory.  Developers should not modify these files by themselves.
When no file is specified, the
.B generate
command will read all the XML and XMI files stored in the
.B db
directory.  It will generate all the models found in those files.
.PP
At the same time, the command generates the SQL files to create the
database tables for the supported drivers (MySQL and SQLite).
For each project, it generates a set of SQL files that can be used
to create or delete the database tables.
.PP
The
.B generate
command is able to read XMI 1.2 model files (UML 1.4) as well as ArgoUML files (.zargo).
The UML model must use the
.I Dynamo
UML profile and assign the
.I Table
,
.I PK
and
.I Bean
stereotypes to the model element for the generation to be activated.
For large or complex UML models, the
.I --package
option allows to activate the generation for the package specified by the option.
In that case, other packages defined by the model are not generated although they could
be referenced and used.
.\"
.SS The propset command
.RS 0
dynamo \fBpropset \fIname value\fR\fR
.RE
.PP
Set a project property to configure some commands provided by
\fBdynamo\fR.  The property is composed of a name and a value.  It is saved in
the
.B dynamo.xml
file.  The following properties are recognized:
.\"
.\"
.SH PROPERTIES
The
.B dynamo.xml
file defines several configuration properties which are used to customize several
commands.  These properties can be modified with the
.B propset
command.
.\"
.SS author
This property defines the author name inserted in file headers.
.\"
.SS author_email
The author email address inserted in file headers.
.\"
.SS gnat.project
The GNAT project file name which is used to build the project.  By default, the GNAT
project file name is the same as the dynamo project name.  This property allows to
specify a different name when the dynamo project name contains characters not allowed
in GNAT project names.
.\"
.SS license
This property controls the license header in file headers.
The following license names are recognized:
.B gpl
.B apache
.B mit
.B bsd3
.\"
.SS search_dirs
This property is generated automatically by
.B dynamo
from the GNAT project paths.  It indicates the search paths
that the Ada Web Application should use to search configuration files,
resource bundles and XHTML presentation files.
.\"
.SS database
The default database connection string.
.\"
.SH FILES
.SS /usr/share/dynamo/base/generator.properties
This configuration file is read by
.I dynamo
to configure various installation parameters necessary for the generation.
.\"
.SS /usr/share/dynamo/base/mappings/AdaMappings.xml
.SS /usr/share/dynamo/base/mappings/MySQLMappings.xml
.SS /usr/share/dynamo/base/mappings/SQLiteMappings.xml
These XML files define the type mapping used in the
.I dynamo
model files.  These mapping indicate for each basic type used in the
XML model files, what is the target Ada, MySQL or SQLite type name.
.\"
.SS /usr/share/dynamo/base/commands
This directory contains XML files that describe additional template commands.
.\"
.SS /usr/share/dynamo/base/templates
This directory contains the template files associated with
.I dynamo
commands.
.\"
.SS /usr/share/dynamo/base/uml
This directory contains the UML profiles that
.I dynamo
reads to obtain global definitions.
.\"
.SH SEE ALSO
\fIgnatmake(1)\fR, \fIgcc(1)\fR, \fIyui-compressor(1)\fR, \fIpngcrush(1)\fR, \fIjpegtran(1)\fR
.\"
.SH AUTHOR
Written by Stephane Carrez.
.\"
